package com.photobucket.webapi.oauth
{
	import flash.net.FileReference;
	import flash.net.URLRequest;
	import flash.net.URLVariables;
	
	/**
	 * Interface for the OAuthRequest object. 
	 * @author jlewark
	 * 
	 */
	public interface IOAuthRequest
	{
		/**
		 * URL of the Request this should not include GET parameters
		 */
		function get url():String;
		function set url(value:String):void;

		/**
		 *  The HTTP method of the request.  
		 *  @default GET
		 *  @see com.photobucket.webapi.oauth.OAuthRequestMethod
		 */
		function get method():String;		
		function set method(value:String):void;
		
		/**
		 *  This flag sets if request needs to be signed with the oauth_token_secret
		 *  this is provided as for most APIs it requires extra work to verify the 
		 *  user has authorized the consumer.  No need to make the API do exta work.
		 */
		function get needsLogin():Boolean;
		function set needsLogin(value:Boolean):void;
		/**
		 * Function to be called on sucessful result from the service. This can be a closure that be used to clean up
		 * the async behavior of a process
		 */
		function get result():Function;
		function set result(value:Function):void;

		/**
		 *  Function to be called on an unsucessful result from the service or a transmission error.  This can be a closure 
		 *  so you can clean up some messy event handler code.
		 */
		function get fault():Function;
		function set fault(value:Function):void;

		/**
		 * Simple Token Object to pass information with the request 
		 */
		function get token():Object;
		function set token(value:Object):void;

		/**
		 * Set File to upload with this request.  This can handle both the FileReference Object from the Flash API
		 * and the File object from AIR that extends it.  This function will also set the method to POST and add
		 * the mystery parameters added by the Flash and AIR runtimes. 
		 * 
		 * @param value FileReference Object to upload
		 * 
		 */		
		function set file(value:FileReference):void;
		function get file():FileReference;
		
				
		/**
		 * Parameter string that can be used as part of the oauth base string 
		 * @return 
		 * 
		 */
		function get parameterString():String;

		/**
		 * Returns a URLVariables object of request in it's current state.  This can be added to URLRequest object's
		 * data property in order to sign it. 
		 * @return 
		 * 
		 */
		function get urlVariables():URLVariables;
		
		/**
		 * Creates a URLRequest object based on OAuthRequest object 
		 * @param request
		 * @return 
		 * 
		 */
		function getURLRequest():URLRequest;
		
		/**
		 * Adds a parameter to the request and they should be key value pairs of strings.  It is not recommeded that 
		 * these be escaped in any way prior to being added to the request.
		 * @param key
		 * @param value
		 * 
		 */
		function addParameter(key:String, value:String):void;
		
	}
}